STRUCT_ASSIGN

The IDL “=” operator is unable to assign a structure value to a structure of a different type. The STRUCT_ASSIGN procedure performs “relaxed structure assignment,” which is a field-by-field copy of a structure to another structure. Fields are copied according to the following rules:

  1. Any fields found in the destination structure that are not found in the source structure are “zeroed” (set to zero, the empty string, or a null pointer or object reference depending on the type of field).
  2. Any fields in the source structure that are not found in the destination structure are quietly ignored.
  3. Any fields that are found in both the source and destination structures are copied one at a time. If necessary, type conversion is done to make their types agree. If a field in the source structure has fewer data elements than the corresponding field in the destination structure, then the “extra” elements in the field in the destination structure are zeroed. If a field in the source structure has more elements than the corresponding field in the destination structure, the extra elements are quietly ignored.

Relaxed structure assignment is especially useful when restoring structures from disk files into an environment where the structure definition has changed. See the description o f the RELAXED_STRUCTURE_ASSIGNMENT keyword to the RESTORE procedure for additional details. Relaxed Structure Assignment provides a more in-depth discussion of the structure-definition process.

Examples

The following example creates two anonymous structures, then uses STRUCT_ASSIGN to insert the contents of the first into the second:

source = { a:FINDGEN(4), b:12 }

dest = { a:INDGEN(2), c:20 }

STRUCT_ASSIGN, /VERBOSE, source, dest

IDL prints:

% STRUCT_ASSIGN: <Anonymous> tag A is longer than destination.

                 The end will be clipped.

% STRUCT_ASSIGN: Destination lacks <Anonymous> tag B. Not copied.

After assignment, dest contains a two-element integer array [0, 1] in its field A and the integer 0 in its field C. Since dest does not have a field B, field B from source is not copied.

Syntax

STRUCT_ASSIGN, Source, Destination [, /NOZERO] [, /VERBOSE]

Arguments

Source

A named variable or element of an array containing a structure, the contents of which will be assigned to the structure specified by the Destination argument. Source can be an object reference if STRUCT_ASSIGN is called inside an object method.

Destination

A named variable containing a structure into which the contents of the structure specified by the Source argument will be inserted. Destination can be an object reference if STRUCT_ASSIGN is called inside an object method.

Keywords

NOZERO

Normally, any fields found in the destination structure that are not found in the source structure are zeroed. Set NOZERO to prevent this action and leave the original contents of such fields unchanged.

VERBOSE

Set this keyword to cause STRUCT_ASSIGN to issue informational messages about any incompatibilities that prevent data from being copied.

Version History

5.1

Introduced